10.2 workflow

Workflow API Reference

The Workflow class represents an executable workflow definition in BindAI.

A workflow organizes nodes into an execution graph, allowing agents, tools, conditions, loops, parallel branches, human tasks, retries, and scheduling to work together as a single automated process.

This page documents the public Workflow API.

---

Overview

A workflow coordinates execution between multiple nodes.

Conceptually:

Start

↓

Workflow Nodes

↓

End

Each node performs a specific task before passing execution to the next node.

---

Creating a Workflow

Workflows are typically created using the WorkflowBuilder.

Example:

builder = WorkflowBuilder()

workflow = builder.build()

Using the builder is the recommended approach because it validates the workflow before execution.

---

Workflow Components

A workflow generally contains:

• workflow identifier
• workflow name
• nodes
• start node
• workflow context
• registered agents
• execution metadata

These components define the workflow’s structure and behavior.

---

WorkflowBuilder

The builder provides a fluent interface for constructing workflows.

Typical methods include:

Method	Purpose
start()	Defines the first node
then()	Connects the next node
add()	Adds an independent node
build()	Validates and returns the workflow

The builder simplifies workflow construction while preventing invalid structures.

---

Executing a Workflow

A workflow is executed through its executor.

Example:

result = workflow.executor.run(
    input="Hello"
)

The executor traverses the workflow graph until execution completes.

---

Workflow Context

Every execution receives a workflow context.

Conceptually:

Input

↓

Workflow Context

↓

Nodes

↓

Output

The context stores variables that are shared between nodes.

---

Workflow Variables

Nodes communicate through workflow variables.

Example:

Agent

↓

result

↓

Condition

↓

approved

Variables remain available throughout workflow execution.

---

Registered Agents

A workflow may contain one or more registered agents.

Workflow

↓

Agent Registry

↓

Agent Nodes

Agent nodes reference registered agents by name.

---

Workflow Nodes

A workflow is composed of nodes.

Common node types include:

• Start
• End
• Agent
• Condition
• Loop
• Parallel
• Human Task

Each node performs a single responsibility within the execution graph.

---

Execution Graph

Nodes are connected to form a directed execution graph.

Node A

↓

Node B

↓

Node C

Some nodes, such as Conditions and Parallel nodes, create multiple outgoing paths.

---

Validation

Before execution, workflows should be validated.

The validator checks for:

• missing start node
• unreachable nodes
• invalid references
• structural errors

Validation helps detect problems during development rather than at runtime.

---

Workflow Result

Workflow execution returns a result object.

Typical information includes:

Property	Description
success	Indicates whether execution completed successfully
output	Workflow variables after execution
error	Execution error, if any

Applications should inspect the result before using workflow outputs.

---

Serialization

Workflows can be serialized for storage or transport.

Typical methods include:

• to_dict()
• load_dict()

Serialization makes it possible to save workflow definitions or exchange them between systems.

---

Human Tasks

If a Human Task node is encountered, execution pauses.

Workflow

↓

Human Task

↓

Waiting

The executor resumes only after the task has been completed.

---

Scheduling

Workflows may be executed manually or by the scheduler.

Workflow Schedule

↓

Workflow

↓

Result

Scheduling is managed separately from workflow execution.

---

Retry and Timeout

Workflows may use execution policies such as:

• RetryPolicy
• TimeoutPolicy

These improve reliability when interacting with external systems.

---

Best Practices

• Build workflows using WorkflowBuilder.
• Keep nodes focused on one responsibility.
• Store shared state in workflow variables.
• Validate workflows before deployment.
• Separate orchestration from AI reasoning.
• Use conditions instead of embedding business logic in prompts.
• Combine retries and timeouts for production workflows.

---

Related APIs

The Workflow API works closely with:

• Agent
• Project
• Tool
• WorkflowBuilder
• WorkflowExecutor

Together these components provide BindAI’s orchestration capabilities.

---

Summary

The Workflow class defines how tasks execute within BindAI.

By organizing nodes into a validated execution graph, workflows enable sequential processing, branching, loops, parallel execution, human approval, scheduling, and other advanced orchestration patterns while keeping business logic modular and reusable.